Compute Engine の「Opsエージェントをインストールする」が上手くいかない！インストールプロセスを理解して解決しよう

Compute Engine 作成時に設定できる便利な Ops エージェントの自動インストール。しかし、インストールがなかなか成功せず困ったことはありませんか？ここでは自動インストールのプロセスについて理解し、主な失敗の原因と解決策について学びます。
#Google Cloud (GCP)
#Cloud Monitoring
#Google Cloud Compute Engine
#Cloud Logging
村田一紘
2024.09.20
 はじめにOps エージェントとは、Compute Engine VM インスタンス内で動作しログ、メトリクスなど様々なテレメトリを収集するエージェントです。

例えば、システムログやジャーナルログを収集して Cloud Logging と連携したり、CPU/メモリ/ディスクやプロセス/ネットワークに関するメトリクスを収集して Cloud Monitoring と連携できます。
https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent?hl=ja
このように Ops エージェントは Compute Engine の運用監視において重要な役割を果たすため、VM インスタンスの作成時にインストールが必要なケースも多いかと思います。

このようなニーズに応えられるよう、Google Cloud コンソールから VM インスタンスを作成する際に簡単に Ops エージェントをインストールできるよう「モニタリングとロギング用の Ops エージェントをインストールする」の設定項目があります。


Compute Engine インスタンスを作成する画面
しかし、Ops エージェントの自動インストール成功には考慮すべき条件が多く、インストールプロセスを理解していないとスムーズにインストールを成功させることは難しいででしょう。かくいう私もよくインストールに失敗して悩んでおりました。。そこで、もう二度と Opsエージェントのインストールで躓かないようブログに記すことにしました。
ここでは Cloud Console から Comupte Engine の VM インスタンス作成時に「モニタリングとロギング用の Ops エージェントをインストールする」にチェックを入れたときのインストールプロセスを紐解き、ハマりやすいポイントについて纏めました。参考にしていただけると幸いです。
 インストールプロセスを紐解くCloud Console による Compute Engine の VM インスタンス作成時に「モニタリングとロギング用の Ops エージェントをインストールする」にチェックを入れて作成すると裏側ではどのような動作が行われるのでしょうか。
まず動作の概要を以下に図示します。


Ops エージェントのインストール 概要
以下より詳細を説明します。
 1. OS Config API が有効になる実は Ops エージェントの自動インストールは VM インスタンス自身の起動スクリプトなどではなく、Compute Engine の VM Manager というサービスの OS ポリシーという機能がトリガーしています。
VM Manager とは、Compute Engine VM インスタンスの OS情報の収集、一元的な自動パッチ適用やソフトウェアインストールなど、複数の VM インスタンス管理を容易にするサービスです。

https://cloud.google.com/compute/docs/vm-manager?hl=ja
VM Manager の OS ポリシー機能は、VM インスタンスのソフトウェア構成のデプロイ、構成、メンテナンス、レポートを自動化して一元化する機能です。

https://cloud.google.com/compute/vm-manager/docs/os-policies?hl=ja
Ops エージェントの自動インストールにこれらの機能を利用するため、OS Config API(osconfig.googleapis.com)が有効化されていない場合は、ここで自動で有効化されます。
 2. VM Manager が制限付きモードで有効になるプロジェクトで VM Manager が有効になっていない場合、VM Manager の制限付きモード(limited functionality mode)が自動で有効になります。
制限付きモードは無償で利用でき Ops エージェントの自動インストールをトリガーできますが、独自のOSポリシーの割り当てを作成したり、パッチ・ジョブを作成したりすることはできません。
制限付きモードの詳細は以下をご参照ください。

https://cloud.google.com/compute/vm-manager/pricing


VM Manager が制限付きモードで有効化される
 3. VM インスタンスで OS Config エージェントが有効になるOS Config エージェントは、VM Manager と インスタンスの情報をやり取りするために VM インスタンスにインストールされるエージェントです。

https://cloud.google.com/compute/vm-manager/docs/overview?hl=ja
OS Config エージェントは、ビルド日付がv20200114以降の CentOS, Container-Optimized OS(COS), Debian、Red Hat Enterprise Linux(RHEL)、Rocky Linux、SLES、Ubuntu、Windows Server の各イメージにデフォルトでインストールされています。

https://cloud.google.com/compute/docs/manage-os?hl=ja#check-install
以下、Debian 12 にて確認した結果です。
$ sudo systemctl status google-osconfig-agent
● google-osconfig-agent.service - Google OSConfig Agent
     Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; preset: enabled)
     Active: active (running) since Fri 2024-09-13 05:02:09 UTC; 1h 40min ago
   Main PID: 480 (google_osconfig)
      Tasks: 9 (limit: 1136)
     Memory: 215.8M
        CPU: 56.413s
     CGroup: /system.slice/google-osconfig-agent.service
             └─480 /usr/bin/google_osconfig_agent
しかし、OS Config エージェントはアイドル状態で起動しており有効化されていません。有効化のためには VM インスタンスのメタデータ enable-osconfig が TRUE となっている必要があります。
ここではインスタンスレベルのメタデータが  enable-osconfig: TRUE となるよう自動で設定されます。


VM インスタンスのメタデータが更新されている
 4. VM Manager で OS ポリシーの割り当てが生成されるOS ポリシーの割り当て(OS Policy Assignment) というリソースが自動生成され、goog-ops-agent-policy という OS ポリシーのアタッチと、管理対象 VM インスタンスを決めるためのターゲットの設定が行われます。
[Compute Engine] -> [OS ポリシー] から [OS ポリシーの割り当て] タブを選択すると、goog-ops-agent-から始まるポリシーの割り当てが確認できます。

対象のポリシーの割り当てをクリックすると以下の画面に遷移します。


自動生成されたOSポリシーの割り当て
goog-ops-agent-policyという OS ポリシーは、様々な OS ディストリビューションに合わせて、インストールする Ops エージェントのリポジトリなどのパッケージ情報が定義されています。

[割り当てられた OS ポリシー]->[goog-ops-agent-policy]->[表示]をクリックすると以下のような情報が確認できます。


OS ポリシー goog-ops-agent-policy の詳細
管理対象 VM インスタンスを決めるためのターゲットは VM インスタンスに設定されたラベルによって決定します。ここで設定されているラベルと同じラベルが設定されている VM インスタンスを管理対象とします。ここではターゲットとするラベルがgoog-ops-agent-policy:v2-x86-template-1-3-0に自動設定されています。
 5. VM インスタンスが VM Manager の管理対象となるようラベルが付与される前述の 4. で設定された OS ポリシーの割り当ての管理対象 VM インスタンスとなるために、VM インスタンスにgoog-ops-agent-policyがキーとなるラベルが自動付与されます。
ここでは、前述の 4. で設定されたターゲットのラベルと同じ goog-ops-agent-policy:v2-x86-template-1-3-0 が設定されています。


VM インスタンスに自動付与されたラベル
 6. OS ポリシーに従い OS Config エージェントが Ops エージェントのインストールを実行ターゲットのラベルと同一のラベルが付与された VM インスタンスに対し、 OS Config エージェント経由で OS ポリシーに定義された Ops エージェントのインストールが実行されます。
例えば OS ディストリビューションが Debian GNU/Linux で、version が 12 の場合を見てみます。
$ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
以下の OS ポリシーが参照されます。


OS ポリシー(debian 12 の場合)
VM インスタンス起動後にジャーナルログを確認すると、OS ポリシーに従い OS Config エージェントが Ops エージェントをインストールする様子が確認できます。
$ sudo journalctl | grep OSConfigAgent
...

# OS ポリシー "goog-ops-agent-policy" を実行
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.7903Z OSConfigAgent Info: Executing policy "goog-ops-agent-policy"

# リポジトリの追加
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8475Z OSConfigAgent Info: Validate: resource "add-repo" validation successful.
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8482Z OSConfigAgent Info: Check state: resource "add-repo" state is NON_COMPLIANT.
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8482Z OSConfigAgent Info: Enforcing repo /etc/apt/sources.list.d/osconfig_managed_143a0c896b.list.
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8485Z OSConfigAgent Info: Enforce state: resource "add-repo" enforcement successful.

### "google-cloud-ops-agent"パッケージのインストール
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8485Z OSConfigAgent Info: Validate: resource "install-pkg" validation successful.
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8870Z OSConfigAgent Info: Check state: resource "install-pkg" state is NON_COMPLIANT.
Sep 20 01:29:56 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:29:56.8876Z OSConfigAgent Info: Installing apt package "google-cloud-ops-agent"
Sep 20 01:30:18 instance-20240920-012822 OSConfigAgent[410]: 2024-09-20T01:30:18.0668Z OSConfigAgent Info: Enforce state: resource "install-pkg" enforcement successful.

...
 7. Cloud Monitoring API / Cloud Logging API との疎通確認Ops エージェントは Cloud Monitoring や Cloud Logging にメトリクスやログ情報を連携します。そのため、Cloud Monitoring API(monitoring.googleapis.com) と Cloud Logging API(logging.googleapis.com) への疎通確認が行われます。
このプロセスを完了することで、Ops エージェントが正常にインストールされたと判断されます。
$ sudo systemctl status google-cloud-ops-agent
● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; preset: enabled)
     Active: active (exited) since Tue 2024-09-17 05:33:55 UTC; 2 days ago
    Process: 395 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -in /etc/google-cloud-ops-agent/config.yaml (code=exited, status=0/SUCCESS)
    Process: 822 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 822 (code=exited, status=0/SUCCESS)
        CPU: 379ms

...

# API へのアクセスチェックを実施
Sep 17 05:33:55 instance-20240913-050036 google_cloud_ops_agent_engine[395]: 2024/09/17 05:33:55 [Ports Check] Result: PASS
Sep 17 05:33:55 instance-20240913-050036 google_cloud_ops_agent_engine[395]: 2024/09/17 05:33:55 [Network Check] Result: PASS
Sep 17 05:33:55 instance-20240913-050036 google_cloud_ops_agent_engine[395]: 2024/09/17 05:33:55 [API Check] Result: PASS
Sep 17 05:33:55 instance-20240913-050036 google_cloud_ops_agent_engine[395]: 2024/09/17 05:33:55 Startup checks finished
 インストール状況の確認Ops エージェントのインストールが問題なく完了しているかどうかは Cloud Console から一元的に確認が可能です。
[Compute Engine] -> [VM インスタンス] から [オブザーバビリティ] のタブを選択し、[探索] をクリックします。


Ops エージェントのインストール確認 1
[リスト] のタブをクリックし、各 VM インスタンスの [エージェント] 列を確認します。緑色のチェックマークに Ops エージェント と記載されていればインストールが正常に完了しています。未検出 となっている場合や、 保留 が数分以上続く場合はインストールが完了できていませんのでトラブルシュートが必要です。


Ops エージェントのインストール確認 2
 トラブルシュートまずは前述のインストールプロセスを理解し、どのステップで失敗しているかを確認することが重要です。ここでは特にハマりがちな問題の原因と対策について2点解説します。
 パッケージリポジトリにアクセスできていないOS Config エージェントが Ops エージェントをインストールするためのパッケージをリポジトリからダウンロードしてくる必要がありますが、リポジトリへのアクセスができない場合にインストールプロセスが失敗します。
リポジトリへのアクセスができないケースは以下の原因が考えられます。
外部IPアドレスが設定されていない
VPC ファイアウォールポリシーで外部向け通信が拒否されている
なお、外部IPアドレスを設定せずにインターネットアクセスを実現するために Cloud NAT を利用できます。Cloud NAT の設定方法については以下をご参照ください。
https://cloud.google.com/nat/docs/gce-example?hl=ja
 Cloud Monitoring API /  Cloud Logging API との疎通ができていないOps エージェントのインストール後に Cloud Monitoring API / Cloud Logging API との疎通確認ができていないと、Ops エージェントのインストール状況が保留のまま遷移しません。
どの API にアクセスできていないかは Ops エージェントのログを確認するといいでしょう。以下のケースですといずれの API チェックにも失敗している状態が確認できます。
$ sudo systemctl status google-cloud-ops-agent
● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; preset: enabled)
     Active: active (exited) since Fri 2024-09-20 02:26:38 UTC; 1h 54min ago

...

# Cloud Monitoring API と Cloud Logging API への API Check が FAIL となっている

2024/09/20 02:26:38 [API Check] Result: FAIL, Error code: MonApiScopeErr, Failure: VM is missing the https://www.googleapis.com/auth/monitoring.write scope., Solution: Add the https://www.googleapis.com/auth/monitoring.write scope to the Compute Engine VM., Resource: https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/authorization
Sep 20 02:26:38 instance-20240920-022457 google_cloud_ops_agent_engine[1516]: 2024/09/20 02:26:38 [API Check] Result: FAIL, Error code: LogApiScopeErr, Failure: VM is missing the https://www.googleapis.com/auth/logging.write scope., Solution: Add the https://www.googleapis.com/auth/logging.write scope to the Compute Engine VM., Resource: https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/authorization
Sep 20 02:26:38 instance-20240920-022457 google_cloud_ops_agent_engine[1516]: 2024/09/20 02:26:38 Startup checks finished
Sep 20 02:26:38 instance-20240920-022457 systemd[1]: Finished google-cloud-ops-agent.service - Google Cloud Ops Agent.
よくある原因としては以下の可能性がありますので確認してみましょう。
Compute Engine に設定するサービスアカウントに「モニタリング指標の書き込み」「ログ書き込み」の IAM ロールが付与されていない。
Compute Engine に設定する Stackdriver Logging API / Stackdriver Monitoring API へのアクセススコープが、「なし」または「読み取りのみ」に設定されている。
まずはサービスアカウントについて解説します。

Ops エージェントが メトリクスやログを Cloud Monitoring API / Cloud Logging API に送信するには、Compute Engine にアタッチするサービスアカウントに対してモニタリング指標の書き込み (roles/monitoring.metricWriter) と ログ書き込み (roles/logging.logWriter) の IAM ロール付与が必要です。
サービスアカウントを指定せずに VM インスタンスを作成する場合、デフォルトではCompute Engine default service accountという名称のサービスアカウントが設定されているため注意しましょう。


Compute Engine のサービスアカウント設定
次にアクセススコープについて解説します。

アクセススコープはサービスアカウントと同様に API へのアクセスを制御する方法の一つですが、ドキュメントによると 「以前の方法(legacy method)」 であるとのことで、基本的にはすべての API をスコープにする(=アクセススコープは API 全許可にし、サービスアカウントで詳細に制御する)ことが推奨のようです。
アクセススコープとそのベストプラクティスについては以下をご参照ください。

https://cloud.google.com/compute/docs/access/service-accounts?_gl=1&hl=ja#accesscopesiam
Ops エージェントから Cloud Monitoring API / Cloud Logging API にアクセスするためには、Stackdriver Logging API / Stackdriver Monitoring API のアクセススコープを「書き込みのみ」または「フル」にすれば良いのですが、前述のベストプラクティスに沿うと 「

すべての Cloud API に完全アクセス権を許可」 にするのが良いかと思います。
API のチェックが OK になると以下のようなログになります。
$ sudo systemctl status google-cloud-ops-agent
● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; preset: enabled)
     Active: active (exited) since Fri 2024-09-20 01:30:17 UTC; 4h 22min ago

...

Sep 20 01:30:17 instance-20240920-012822 google_cloud_ops_agent_engine[1517]: 2024/09/20 01:30:17 [Ports Check] Result: PASS
Sep 20 01:30:17 instance-20240920-012822 google_cloud_ops_agent_engine[1517]: 2024/09/20 01:30:17 [Network Check] Result: PASS
Sep 20 01:30:17 instance-20240920-012822 google_cloud_ops_agent_engine[1517]: 2024/09/20 01:30:17 [API Check] Result: PASS
Sep 20 01:30:17 instance-20240920-012822 google_cloud_ops_agent_engine[1517]: 2024/09/20 01:30:17 Startup checks finished
Sep 20 01:30:17 instance-20240920-012822 systemd[1]: Finished google-cloud-ops-agent.service - Google Cloud Ops Agent.
 さいごにOps エージェントの自動インストールは裏側では様々なコンポーネントが連携しあって動作していることがわかったと思います。そのため、こちらで紹介した原因以外にも Ops エージェントのインストールや動作に関して注意すべき点は多々存在します。詳細なトラブルシュートは以下を参考にしてみてください。
https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/troubleshooting?hl=ja
本ブログを読んでいただきインストールプロセスを把握してから上記ドキュメントを読み進めていただくと、エラーの原因や解決方法が納得できてくるかと思います。